---
title: Colors
description: Learn how to configure and customize colors with HeroUI.
---

# Colors

HeroUI's plugin enables you to personalize the semantic colors of the theme such as `primary`,
`secondary`, `success`, etc.

<CarbonAd/>

<Spacer y={4} />

```js {7,11}
module.exports = {
  plugins: [
    heroui({
      themes: {
        light: {
          // ...
          colors: {},
        },
        dark: {
          // ...
          colors: {},
        },
        // ... custom themes
      },
    }),
  ],
};
```



> **Note**: Colors configurations apply globally across all components.

## Default Colors

HeroUI offers a default color palette right out of the box, perfect for when you're 
still undecided about your specific branding colors.

These colors are split into [Common Colors](#common-colors) and [Semantic Colors](#semantic-colors).

- [Common Colors](#common-colors): Consistent across themes.
- [Semantic Colors](#semantic-colors): Adjust according to the chosen theme.

### Common Colors

Common colors, like [TailwindCSS](https://v3.tailwindcss.com/docs/customizing-colors) colors, 
remain consistent regardless of the theme. 

To prevent conflicts with TailwindCSS colors, common colors are initially disabled but can 
be activated with the `addCommonColors` option.

```js {4}
module.exports = {
  plugins: [
    heroui({
      addCommonColors: true,
    }),
  ],
};
```

Enabling this option supplements some TailwindCSS default colors with the following:

```js
module.exports = {
  theme: {
    extend: {
      colors: {
        white: "#FFFFFF",
        black: "#000000",
        blue: {
          50: "#e6f1fe",
          100: "#cce3fd",
          200: "#99c7fb",
          300: "#66aaf9",
          400: "#338ef7",
          500: "#006FEE",
          600: "#005bc4",
          700: "#004493",
          800: "#002e62",
          900: "#001731",
        },
        // .. rest of the colors
      },
    },
  },
};
```

<CommonColors />

### Semantic Colors

Semantic colors adapt with the theme, delivering meaning and reinforcing your brand identity.

For an effective palette, we recommend using color ranges from `50` to `900`. You can use tools like [Eva Design System](https://colors.eva.design/),
[Smart Watch](https://smart-swatch.netlify.app/), [Palette](https://palettte.app/) or [Color Box](https://colorbox.io/) to generate your palette.

> Semantic colors should be placed inside the `heroui` plugin options, not inside the TailwindCSS theme object.

```js {7-13,19-25,33-37}
module.exports = {
  plugins: [
    heroui({
      themes: {
        light: {
          colors: {
            background: "#FFFFFF", // or DEFAULT
            foreground: "#11181C", // or 50 to 900 DEFAULT
            primary: {
              //... 50 to 900
              foreground: "#FFFFFF",
              DEFAULT: "#006FEE",
            },
            // ... rest of the colors
          },
        },
        dark: {
          colors: {
            background: "#000000", // or DEFAULT
            foreground: "#ECEDEE", // or 50 to 900 DEFAULT
            primary: {
              //... 50 to 900
              foreground: "#FFFFFF",
              DEFAULT: "#006FEE",
            },
          },
          // ... rest of the colors
        },
        mytheme: {
          // custom theme
          extend: "dark",
          colors: {
            primary: {
              DEFAULT: "#BEF264",
              foreground: "#000000",
            },
            focus: "#BEF264",
          },
        },
      },
    }),
  ],
};
```

<Blockquote className="flex items-center gap-2">
  Change the docs theme to see the semantic colors in action.
  <ThemeSwitch />
</Blockquote>

<SemanticColors />

### Using Semantic Colors

Semantic colors can be applied anywhere in your project where colors are used, such as 
text color, border color, background color utilities, and more.

```html
<div class="bg-primary-500 text-primary-50 rounded-small px-2 py-1">
  This is a primary color box
</div>
```

<Spacer y={4} />

import semanticColorsExample from "@/content/customization/colors/semantic-colors";

<CodeDemo title="Semantic Colors Example" showEditor={false} files={semanticColorsExample} />

### Javascript Variables

Import semantic and common colors into your JavaScript files as follows:

```js
import {commonColors, semanticColors} from "@heroui/theme";

console.log(commonColors.white); // #FFFFFF
console.log(commonColors.blue[500]); // #006FEE

console.log(semanticColors.dark.warning.DEFAULT); // #FFC107
console.log(semanticColors.light.primary.DEFAULT); // #006FEE
```

### CSS Variables

HeroUI creates CSS variables using the format `--prefix-colorname-shade` for each semantic color. By
default the prefix is `heroui`, but you can change it with the `prefix` option.

```js {4}
module.exports = {
  plugins: [
    heroui({
      prefix: "myapp",
    }),
  ],
};
```

Then you can use the CSS variables in your CSS files.

```css
/* With default prefix */
.my-component {
  background-color: hsl(var(--heroui-primary-500));
}
/*  With custom prefix */
.my-component {
  background-color: hsl(var(--myapp-primary-500));
}
```
